home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / cmidilib.zip / MIDIFILE.DOC < prev    next >
Text File  |  1991-08-23  |  14KB  |  463 lines
  1.  
  2.  
  3.  
  4. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      mfread,mfwrite - read and write a standard MIDI file
  10.  
  11. SYNOPSIS
  12.      #include "mfread.h"
  13.  
  14.      mfread ()
  15.  
  16.      int (*Mf_getc) ();
  17.      int (*Mf_putc) ();
  18.      int (*Mf_error) (char *msg);
  19.      int (*Mf_header) (int format, int ntrks, int division);
  20.      int (*Mf_trackstart) ();
  21.      int (*Mf_trackend) ();
  22.      int (*Mf_noteon) (int chan, int pitch, int vol);
  23.      int (*Mf_noteoff) (int chan, int pitch, int vol);
  24.      int (*Mf_pressure) (int chan, int pitch, int pressure);
  25.      int (*Mf_parameter) (int chan, int control, int value);
  26.      int (*Mf_pitchbend) (int chan, int msb, int lsb);
  27.      int (*Mf_program) (int chan, int program);
  28.      int (*Mf_chanpressure) (int chan, int pressure);
  29.      int (*Mf_sysex) (int leng, char *msg);
  30.      int (*Mf_metamisc) (int type, int leng, int msg);
  31.      int (*Mf_seqspecific) (int type, int leng, int msg);
  32.      int (*Mf_seqnum) (int num);
  33.      int (*Mf_text) (int type, int leng, int msg);
  34.      int (*Mf_eot) ();
  35.      int (*Mf_timesig) (int numer, int denom, int clocks, int qnotes);
  36.      int (*Mf_smpte) (int hour, int min, int sec, int frame, int fract);
  37.      int (*Mf_tempo) (int microsecs);
  38.      int (*Mf_keysig) (int sharpflat, int minor);
  39.      int (*Mf_arbitrary) (int leng, int msg);
  40.      int Mf_nomerge;
  41.      long Mf_currtime;
  42.  
  43.      mfwrite(int format, int ntracks, int division, FILE *fp)
  44.  
  45.      int (*Mf_writetrack)(int track);
  46.      int (*Mf_writetempotrack)();
  47.  
  48.      void mf_write_midi_event(delta, type, chan, data, size)
  49.      unsigned long delta;
  50.      unsigned int type,chan,size;
  51.      char *data;
  52.  
  53.      void mf_write_meta_event(delta, type, data, size)
  54.      unsigned long delta;
  55.      unsigned int type,chan,size;
  56.      char *data;
  57.  
  58.      void mf_write_tempo(tempo)
  59.      unsigned long tempo;
  60.  
  61.  
  62.  
  63. Sun Release 4.1           Last change:                          1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  71.  
  72.  
  73.  
  74.      unsigned long mf_sec2ticks(float seconds, int division, int tempo)
  75.      float seconds;
  76.      int division;
  77.      unsigned int tempo;
  78.  
  79.      float mf_ticks2sec(ticks, division, tempo)
  80.      unsigned long ticks;
  81.      int division;
  82.      unsigned int tempo;
  83.  
  84.  
  85. DESCRIPTION
  86.      The mfread function reads  and  inteprets  a  standard  MIDI
  87.      file.   To use it you need to understand the general form of
  88.      a MIDI file and the type of information it contains, but you
  89.      don't  need  to  know  much, if anything, about the detailed
  90.      format of the file and the mechanics of reading it  reliably
  91.      and portably.
  92.  
  93.      The mfwrite function writes a standard MIDI file making  use
  94.      of  user-defined  functions  that  access the program's data
  95.      structure.   To  use  it  you  need  to  define   your   own
  96.      Mf_writetrack  routine and then make use of the write_* fam-
  97.      ily of routines to write out the  MIDI  data.   The  mfwrite
  98.      routine  takes  care of the file format and writing the file
  99.      and track chunk headers.
  100.  
  101.  
  102. READING STANDARD MIDI FILES
  103.      A single call to mfread will read an entire MIDI file.   The
  104.      interface  to  mfread  is  a set of external variables named
  105.      Mf_*, most of which are function pointers to be called  from
  106.      within  mfread  during the process of parsing the MIDI file.
  107.      Before calling mfread, the  only  requirement  is  that  you
  108.      assign  a  value  to  Mf_getc - a pointer to a function that
  109.      will return characters from the MIDI file, using -1 to indi-
  110.      cate  EOF.   All  the rest of the function pointers are ini-
  111.      tialized to NULL, and the default action for each is  to  do
  112.      nothing.   The  following is a complete program using mfread
  113.      that could serve as a 'syntax checker' for MIDI files:
  114.  
  115.                #include <stdio.h>
  116.                #include "midifile.h"
  117.  
  118.                mygetc()
  119.                {
  120.                     /* use standard input */
  121.                     return(getchar());
  122.                }
  123.  
  124.                main()
  125.                {
  126.  
  127.  
  128.  
  129. Sun Release 4.1           Last change:                          2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  137.  
  138.  
  139.  
  140.                     Mf_getc = mygetc;
  141.                     mfread();
  142.                     exit(0);
  143.                }
  144.  
  145.      This takes advantage of the default action when an error  is
  146.      detected, which is to exit silently with a return code of 1.
  147.      An error function of your own can be used by giving a  value
  148.      to Mf_error; the function will be called with the error mes-
  149.      sage as an argument.  The other Mf_* variables can similarly
  150.      be  used  to call arbitrary functions while parsing the MIDI
  151.      file.  The descriptions below of the information  passed  to
  152.      these  functions  is sparse; refer to the MIDI file standard
  153.      for the complete descriptions.
  154.  
  155.      Mf_header is the first function to be called, and its  argu-
  156.      ments  contain  information from the MIDI file's header; the
  157.      format (0,1, or 2), the number of tracks, and  the  division
  158.      of   a   quarter-note   that   defines   the   times  units.
  159.      Mf_trackstart and Mf_trackend are called  at  the  beginning
  160.      and end of each track.
  161.  
  162.      Once inside a track, each separate message causes a function
  163.      to  be  called.   For  example,  each note-on message causes
  164.      Mf_noteon to be called with the channel, pitch,  and  volume
  165.      as  arguments.   The  time  at which the message occurred is
  166.      stored in Mf_currtime - one of the  few  external  variables
  167.      that  isn't  a function pointer.  The other channel messages
  168.      are handled in a similar and obvious fashion  -  Mf_noteoff,
  169.      Mf_pressure,  Mf_parameter,  Mf_pitchbend,  Mf_program,  and
  170.      Mf_chanpressure.  See the declarations above for  the  argu-
  171.      ments that are passed to each.
  172.  
  173.      System exclusive messages are handled by  calling  Mf_sysex,
  174.      passing  as  arguments the message length and a pointer to a
  175.      static buffer containing the entire message.  The buffer  is
  176.      expanded  when  necessary;  memory  availability is the only
  177.      limit to its size.  Normally, 'continued' system  exclusives
  178.      are  automatically merged, and Mf_sysex is only called once.
  179.      It you want to disable this you can  set  Mf_nomerge  to  1,
  180.      causing Mf_sysex to be called once for each part of the mes-
  181.      sage.
  182.  
  183.      Mf_seqnum is called by the  meta  message  that  provides  a
  184.      sequence  number, which if present must appear at the begin-
  185.      ning of a track.  The tempo meta message causes Mf_tempo  to
  186.      be  called;  its  argument is the number of microseconds per
  187.      MIDI quarter-note (24 MIDI clocks).  The  end-of-track  meta
  188.      message  causes Mf_eot to be called.  The key signature meta
  189.      message causes Mf_keysig to be called;  the  first  argument
  190.      conveys  the  number of sharps or flats, the second argument
  191.      is 1 if the key is minor.
  192.  
  193.  
  194.  
  195. Sun Release 4.1           Last change:                          3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  203.  
  204.  
  205.  
  206.      The Mf_timesig and Mf_smpte functions are  called  when  the
  207.      corresponding  meta  messages  are  seen.  See the MIDI file
  208.      standard for a description of their arguments.
  209.  
  210.      The text messages in the MIDI file standard are of the  fol-
  211.      lowing types:
  212.  
  213.                0x01      Text Event
  214.                0x02      Copyright
  215.                0x03      Sequence/Track Name
  216.                0x04      Instrument
  217.                0x05      Lyric
  218.                0x06      Marker
  219.                0x07      Cue Point
  220.                0x08-0x0F Reserverd but Undefined
  221.  
  222.      Mf_text is called for each of these; the arguments  are  the
  223.      type  number,  the message length, and a pointer to the mes-
  224.      sage buffer.
  225.  
  226.      Misceallaneous meta messages  are  handled  by  Mf_metamisc,
  227.      sequencer-specific  messages  are handled by Mf_seqspecific,
  228.      and arbitrary "escape" messages (started with 0xF7) are han-
  229.      dled by Mf_arbitrary.
  230.  
  231. READING EXAMPLE
  232.      The following is a strings-like program for MIDI files:
  233.  
  234.                #include <stdio.h>
  235.                #include <ctype.h>
  236.                #include "midifile.h"
  237.  
  238.                FILE *F;
  239.  
  240.                mygetc() { return(getc(F)); }
  241.  
  242.                mytext(type,leng,msg)
  243.                char *msg;
  244.                {
  245.                     char *p;
  246.                     char *ep = msg + leng;
  247.  
  248.                     for ( p=msg; p<ep ; p++ )
  249.                          putchar( isprint(*p) ? *p : '?' );
  250.                     putchar('0);
  251.                }
  252.  
  253.                main(argc,argv)
  254.                char **argv;
  255.                {
  256.                     if ( argc > 1 )
  257.                          F = fopen(argv[1],"r");
  258.  
  259.  
  260.  
  261. Sun Release 4.1           Last change:                          4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  269.  
  270.  
  271.  
  272.                     else
  273.                          F = stdin;
  274.  
  275.                     Mf_getc = mygetc;
  276.                     Mf_text = mytext;
  277.  
  278.                     mfread();
  279.  
  280.                     exit(0);
  281.                }
  282.  
  283.  
  284. WRITING STANDARD MIDI FILES
  285.      A single call to mfwrite will write  an  entire  MIDI  file.
  286.      Before  calling  mfwrite, you must assign values to function
  287.      pointers Mf_writetrack and Mf_putc.  The first is a  routine
  288.      to  access  your  MIDI data structure, which can make use of
  289.      other library routines to write the actual MIDI  data.   The
  290.      routine  Mf_writetrack  will  be  passed  a single parameter
  291.      which is the number of the track to be written.  The pointer
  292.      Mf_putc  should  be set to point to a routine that accepts a
  293.      charcter as input, writes that  character  to  a  file,  and
  294.      returns the value that was written.  In the case of a format
  295.      1 file, a routine has to be written to write  a  tempo  map,
  296.      and  assigned  to  the  function pointer Mf_writetempotrack.
  297.      This is because format 1 files assume the first track  writ-
  298.      ten is a tempo track.
  299.  
  300.      mf_write_midi_event  and  mf_write_meta_event  are  routines
  301.      that  should  be  called  from your Mf_writetrack routine to
  302.      write out MIDI events.  The delta time param is  the  number
  303.      of  ticks  since the last event.  The int "type" is the type
  304.      of MIDI message. The int "chan" is the MIDI  channel,  which
  305.      can  be between 1 and 16.  The char pointer "data" points to
  306.      an array containing the data bytes, if any  exist.  The  int
  307.      "size" is the number of data bytes.
  308.  
  309.      mf_sec2ticks and mf_ticks2sec are utility routines  to  help
  310.      you convert between the MIDI file parameter of ticks and the
  311.      more standard seconds. The int "division" is the same  divi-
  312.      sion  parameter from the file header, and tempo is expressed
  313.      in microseconds  per  MIDI  quarter-note,  or  "24ths  of  a
  314.      microsecond  per MIDI clock". The division has two meanings,
  315.      depending on whether bit 15 is set or not.   If  bit  15  of
  316.      division  is zero, bits 14 through 0 represent the number of
  317.      delta-time "ticks" which make up a quarter note.  If bit  15
  318.      of  division  is  a one, delta-times in a file correspond to
  319.      subdivisions of a second similiar to  SMPTE  and  MIDI  time
  320.      code.  In  this format bits 14 through 8 contain one of four
  321.      values - 24, -25, -29, or -30,  corresponding  to  the  four
  322.      standard  SMPTE and MIDI time code frame per second formats,
  323.      where  -29  represents  30  drop  frame.   The  second  byte
  324.  
  325.  
  326.  
  327. Sun Release 4.1           Last change:                          5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  335.  
  336.  
  337.  
  338.      consisting  of  bits 7 through 0 corresponds the the resolu-
  339.      tion within a frame.  Refer the Standard MIDI Files 1.0 spec
  340.      for more details.
  341.  
  342.  
  343. WRITING EXAMPLE
  344.      The following is a simple  program  to  demonstrate  writing
  345.      MIDI  files.  The track would consist of a series of quarter
  346.      notes from lowest to highest in pitch at constant  velocity,
  347.      each separted by a quarter-note rest.
  348.  
  349.                #include <stdio.h>
  350.                #include <ctype.h>
  351.                #include "midifile.h"
  352.  
  353.                FILE *fp;
  354.                myputc(c) { return(putc(c,fp));}
  355.  
  356.                int mywritetrack(track)
  357.                int track;
  358.                {
  359.                    int i;
  360.                    char data[2];
  361.  
  362.                    /* 120 beats/per/second */
  363.                    mf_write_tempo((long)500000);
  364.  
  365.                    for(i = 1 ; i < 128; i++){
  366.                       data[0] = i; /* note number */
  367.                       data[1] = 64; /* velocity */
  368.                       if(!mf_write_midi_event(480,note_on,1,data,2))
  369.                        return(-1);
  370.                       if(!mf_write_midi_event(480,note_off,1,data,2))
  371.                           return(-1);
  372.                    }
  373.  
  374.                    return(1);
  375.                } /* end of write_track() */
  376.  
  377.                main(argc,argv)
  378.                char **argv;
  379.                {
  380.                    if((fp = fopen(argv[1],"w")) == 0L)
  381.                     exit(1);
  382.  
  383.                    Mf_putc = myputc;
  384.                    Mf_writetrack = mywritetrack;
  385.  
  386.                    /* write a single track */
  387.                    mfwrite(0,1,480,fp);
  388.                }
  389.  
  390.  
  391.  
  392.  
  393. Sun Release 4.1           Last change:                          6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. MIDIFILE(3)            C LIBRARY FUNCTIONS            MIDIFILE(3)
  401.  
  402.  
  403.  
  404. AUTHOR
  405.      Tim Thompson (att!twitch!glimmer!tjt)
  406.  
  407. CONTRIBUTORS
  408.      Michael Czeiszperger (mike@pan.com)
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459. Sun Release 4.1           Last change:                          7
  460.  
  461.  
  462.  
  463.